<template><div><h2 id="别名-aliases" tabindex="-1"><a class="header-anchor" href="#别名-aliases"><span>别名（Aliases）</span></a></h2>
<p>别名用来表示文件路径和 URL，这样就避免了在代码中硬编码一些绝对路径和 URL。一个别名必须以 <code v-pre>@</code> 字符开头，以区别于传统的文件路径和 URL。没有前导 <code v-pre>@</code> 定义的别名将以 <code v-pre>@</code> 字符作为前缀。</p>
<p>Yii 预定义了大量可用的别名。例如，别名 <code v-pre>@yii</code> 指的是 Yii 框架本身的安装目录， 而 <code v-pre>@web</code> 表示的是当前运行应用的根 URL。</p>
<h2 id="定义别名" tabindex="-1"><a class="header-anchor" href="#定义别名"><span>定义别名</span></a></h2>
<p>你可以调用 [[Yii::setAlias()]] 来给文件路径或 URL 定义别名：</p>
<div class="language-php line-numbers-mode" data-highlighter="prismjs" data-ext="php" data-title="php"><pre v-pre class="language-php"><code><span class="line"><span class="token comment">// 文件路径的别名</span></span>
<span class="line"><span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">setAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@foo'</span><span class="token punctuation">,</span> <span class="token string single-quoted-string">'/path/to/foo'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line"></span>
<span class="line"><span class="token comment">// URL 的别名</span></span>
<span class="line"><span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">setAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@bar'</span><span class="token punctuation">,</span> <span class="token string single-quoted-string">'http://www.example.com'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line"></span>
<span class="line"><span class="token comment">// 包含 \foo\Bar 类的具体文件的别名</span></span>
<span class="line"><span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">setAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@foo/Bar.php'</span><span class="token punctuation">,</span> <span class="token string single-quoted-string">'/definitely/not/foo/Bar.php'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><blockquote>
<p>Note: 别名所指向的文件路径或 URL 不一定是真实存在的文件或资源。</p>
</blockquote>
<p>可以通过在一个别名后面加斜杠 <code v-pre>/</code> 和一至多个路径分段生成新别名（无需调用 [[Yii::setAlias()]]）。我们把通过 [[Yii::setAlias()]] 定义的别名称为 <strong>根别名</strong>，而用他们衍生出去的别名成为 <strong>衍生别名</strong>。例如，<code v-pre>@foo</code> 就是根别名，而 <code v-pre>@foo/bar/file.php</code> 是一个衍生别名。</p>
<p>你还可以用别名去定义新别名（根别名与衍生别名均可）：</p>
<div class="language-php line-numbers-mode" data-highlighter="prismjs" data-ext="php" data-title="php"><pre v-pre class="language-php"><code><span class="line"><span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">setAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@foobar'</span><span class="token punctuation">,</span> <span class="token string single-quoted-string">'@foo/bar'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><p>根别名通常在 <a href="https://github.com/yiisoft/yii2/blob/master/docs/guide-zh-CN/runtime-bootstrapping.md" target="_blank" rel="noopener noreferrer">引导</a> 阶段定义。比如，你可以在 <a href="https://github.com/yiisoft/yii2/blob/master/docs/guide-zh-CN/structure-entry-scripts.md" target="_blank" rel="noopener noreferrer">入口脚本</a> 里调用 [[Yii::setAlias()]]。为了方便起见，<a href="https://github.com/yiisoft/yii2/blob/master/docs/guide-zh-CN/structure-applications.md" target="_blank" rel="noopener noreferrer">应用</a> 提供了一个名为 <code v-pre>aliases</code> 的可写属性，你可以在应用 <a href="https://github.com/yiisoft/yii2/blob/master/docs/guide-zh-CN/concept-configurations.md" target="_blank" rel="noopener noreferrer">配置</a> 中设置它，就像这样：</p>
<div class="language-php line-numbers-mode" data-highlighter="prismjs" data-ext="php" data-title="php"><pre v-pre class="language-php"><code><span class="line"><span class="token keyword">return</span> <span class="token punctuation">[</span></span>
<span class="line">    <span class="token comment">// ...</span></span>
<span class="line">    <span class="token string single-quoted-string">'aliases'</span> <span class="token operator">=></span> <span class="token punctuation">[</span></span>
<span class="line">        <span class="token string single-quoted-string">'@foo'</span> <span class="token operator">=></span> <span class="token string single-quoted-string">'/path/to/foo'</span><span class="token punctuation">,</span></span>
<span class="line">        <span class="token string single-quoted-string">'@bar'</span> <span class="token operator">=></span> <span class="token string single-quoted-string">'http://www.example.com'</span><span class="token punctuation">,</span></span>
<span class="line">    <span class="token punctuation">]</span><span class="token punctuation">,</span></span>
<span class="line"><span class="token punctuation">]</span><span class="token punctuation">;</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><h2 id="解析别名" tabindex="-1"><a class="header-anchor" href="#解析别名"><span>解析别名</span></a></h2>
<p>你可以调用 [[Yii::getAlias()]] 命令来解析根别名到对应的文件路径或 URL。同样的页面也可以用于解析衍生别名。例如：</p>
<div class="language-php line-numbers-mode" data-highlighter="prismjs" data-ext="php" data-title="php"><pre v-pre class="language-php"><code><span class="line"><span class="token keyword">echo</span> <span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">getAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@foo'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>               <span class="token comment">// 输出：/path/to/foo</span></span>
<span class="line"><span class="token keyword">echo</span> <span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">getAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@bar'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>               <span class="token comment">// 输出：http://www.example.com</span></span>
<span class="line"><span class="token keyword">echo</span> <span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">getAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@foo/bar/file.php'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>  <span class="token comment">// 输出：/path/to/foo/bar/file.php</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>由衍生别名所解析出的文件路径或 URL 是通过替换掉衍生别名中的根别名部分得到的。</p>
<blockquote>
<p>Note: [[Yii::getAlias()]] 并不检查结果路径或 URL 所指向的资源是否真实存在。</p>
</blockquote>
<p>根别名可能也会包含斜杠 <code v-pre>/</code>。[[Yii::getAlias()]] 足够智能到判断一个别名中的哪部分是根别名，因此能正确解析文件路径或 URL。例如：</p>
<div class="language-php line-numbers-mode" data-highlighter="prismjs" data-ext="php" data-title="php"><pre v-pre class="language-php"><code><span class="line"><span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">setAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@foo'</span><span class="token punctuation">,</span> <span class="token string single-quoted-string">'/path/to/foo'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line"><span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">setAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@foo/bar'</span><span class="token punctuation">,</span> <span class="token string single-quoted-string">'/path2/bar'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line"><span class="token keyword">echo</span> <span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">getAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@foo/test/file.php'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>  <span class="token comment">// 输出：/path/to/foo/test/file.php</span></span>
<span class="line"><span class="token keyword">echo</span> <span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">getAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@foo/bar/file.php'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>   <span class="token comment">// 输出：/path2/bar/file.php</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>若 <code v-pre>@foo/bar</code> 未被定义为根别名，最后一行语句会显示为 <code v-pre>/path/to/foo/bar/file.php</code>。</p>
<h2 id="使用别名" tabindex="-1"><a class="header-anchor" href="#使用别名"><span>使用别名</span></a></h2>
<p>别名在 Yii 的很多地方都会被正确识别，无需调用 [[Yii::getAlias()]] 来把它们转换为路径/URL。例如，[[yii\caching\FileCache::cachePath]] 能同时接受文件路径或是指向文件路径的别名，因为通过 <code v-pre>@</code> 前缀能区分它们。</p>
<div class="language-php line-numbers-mode" data-highlighter="prismjs" data-ext="php" data-title="php"><pre v-pre class="language-php"><code><span class="line"><span class="token keyword">use</span> <span class="token package">yii<span class="token punctuation">\</span>caching<span class="token punctuation">\</span>FileCache</span><span class="token punctuation">;</span></span>
<span class="line"></span>
<span class="line"><span class="token variable">$cache</span> <span class="token operator">=</span> <span class="token keyword">new</span> <span class="token class-name">FileCache</span><span class="token punctuation">(</span><span class="token punctuation">[</span></span>
<span class="line">    <span class="token string single-quoted-string">'cachePath'</span> <span class="token operator">=></span> <span class="token string single-quoted-string">'@runtime/cache'</span><span class="token punctuation">,</span></span>
<span class="line"><span class="token punctuation">]</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div><div class="line-number"></div></div></div><p>请关注 API 文档了解特定属性或方法参数是否支持别名。</p>
<h2 id="预定义别名" tabindex="-1"><a class="header-anchor" href="#预定义别名"><span>预定义别名</span></a></h2>
<p>Yii 预定义了一系列别名来简化常用路径和 URL 的使用：</p>
<ul>
<li><code v-pre>@yii</code>，<code v-pre>BaseYii.php</code> 文件所在的目录（也被称为框架安装目录）。</li>
</ul>
<p><code v-pre>@yii</code> 别名是在 <a href="https://github.com/yiisoft/yii2/blob/master/docs/guide-zh-CN/structure-entry-scripts.md" target="_blank" rel="noopener noreferrer">入口脚本</a> 里包含 <code v-pre>Yii.php</code> 文件时定义的，其他的别名都是在 <a href="https://github.com/yiisoft/yii2/blob/master/docs/guide-zh-CN/concept-configurations.md" target="_blank" rel="noopener noreferrer">配置应用</a> 的时候，于应用的构造方法内定义的。</p>
<ul>
<li><code v-pre>@vendor</code>，[[yii\base\Application::vendorPath]] Composer 管理的依赖包目录。</li>
<li><code v-pre>@bower</code>，包含 <a href="http://bower.io/" target="_blank" rel="noopener noreferrer">bower 包</a> 的根目录。默认为 <code v-pre>@vendor/bower</code>。</li>
<li><code v-pre>@npm</code>，包含 <a href="https://www.npmjs.com/" target="_blank" rel="noopener noreferrer">npm 包</a> 的根目录。默认为 <code v-pre>@vendor/npm</code>。</li>
<li><code v-pre>@webroot</code>，当前运行的 Web 应用程序的 Web 根目录。它是根据包含 <a href="https://github.com/yiisoft/yii2/blob/master/docs/guide-zh-CN/structure-entry-scripts.md" target="_blank" rel="noopener noreferrer">入口脚本</a> 的目录确定的。</li>
<li><code v-pre>@web</code>，当前运行的Web应用程序的基础 URL。它的值与 [[yii\web\Request::baseUrl]] 相同。</li>
</ul>
<blockquote>
<p>Note: <code v-pre>@web</code> 和 <code v-pre>@webroot</code> 别名，因为它们的描述表明是在 [[yii\web\Application]] Web 应用中定义的，因此默认情况下不适用于 [[yii\console\Application]] 控制台应用程序。</p>
</blockquote>
<h3 id="基础应用模板" tabindex="-1"><a class="header-anchor" href="#基础应用模板"><span>基础应用模板</span></a></h3>
<ul>
<li><code v-pre>@app</code>，当前运行的应用 [[yii\base\Application::basePath]] 根路径。</li>
<li><code v-pre>@runtime</code>，当前运行的应用的 [[yii\base\Application::runtimePath]] 运行环境路径，默认为 <code v-pre>@app/runtime</code>。</li>
</ul>
<h3 id="高级应用模板" tabindex="-1"><a class="header-anchor" href="#高级应用模板"><span>高级应用模板</span></a></h3>
<ul>
<li><code v-pre>@common</code> - 公共目录。</li>
<li><code v-pre>@frontend</code> - 前台 Web 应用程序目录。</li>
<li><code v-pre>@backend</code> - 后台 Web 应用程序目录。</li>
<li><code v-pre>@console</code> - 控制台目录。</li>
</ul>
<p>对应衍生的还有 <code v-pre>@frontend/runtime</code>、<code v-pre>@backend/runtime</code>、<code v-pre>@console/runtime</code> 等。<br>
特定于高级应用程序的目录结构的别名<br>
(<code v-pre>@common</code>, <code v-pre>@frontend</code>, <code v-pre>@backend</code>, 以及 <code v-pre>@console</code>) 在 <code v-pre>common/config/bootstrap.php</code> 文件中定义。</p>
<h2 id="扩展别名" tabindex="-1"><a class="header-anchor" href="#扩展别名"><span>扩展别名</span></a></h2>
<p>每一个通过 Composer 安装的 <a href="https://github.com/yiisoft/yii2/blob/master/docs/guide-zh-CN/structure-extensions.md" target="_blank" rel="noopener noreferrer">扩展</a> 都自动添加了一个别名。该别名会以该扩展在 <code v-pre>composer.json</code> 文件中所声明的根命名空间为名，且他直接代指该包的根目录。例如，如果你安装有 <code v-pre>yiisoft/yii2-jui</code> 扩展，会自动得到 <code v-pre>@yii/jui</code> 别名，它定义于 <a href="https://github.com/yiisoft/yii2/blob/master/docs/guide-zh-CN/runtime-bootstrapping.md" target="_blank" rel="noopener noreferrer">引导启动</a> 阶段：</p>
<div class="language-php line-numbers-mode" data-highlighter="prismjs" data-ext="php" data-title="php"><pre v-pre class="language-php"><code><span class="line"><span class="token class-name static-context">Yii</span><span class="token operator">::</span><span class="token function">setAlias</span><span class="token punctuation">(</span><span class="token string single-quoted-string">'@yii/jui'</span><span class="token punctuation">,</span> <span class="token string single-quoted-string">'VendorPath/yiisoft/yii2-jui'</span><span class="token punctuation">)</span><span class="token punctuation">;</span></span>
<span class="line"></span></code></pre>
<div class="line-numbers" aria-hidden="true" style="counter-reset:line-number 0"><div class="line-number"></div></div></div><blockquote>
<p>💖喜欢本文档的，欢迎点赞、收藏、留言或转发，谢谢支持！<br>
作者邮箱：zhuzixian520@126.com，github地址：<a href="https://github.com/zhuzixian520" target="_blank" rel="noopener noreferrer">github.com/zhuzixian520</a></p>
</blockquote>
</div></template>


